Aminet 16/Aminet 16 (1996)(GTI - Schatztruhe)[!][Dec 1996].iso/Aminet/comm/bbs/TA1_22.lha/Programming/trans_lib.doc

Text File | 1992-03-19 | 20KB | 588 lines

TABLE OF CONTENTS

transamiga.library/ANSIWrite
transamiga.library/BBSCmd
transamiga.library/BBSLineInfo
transamiga.library/CheckCarrier
transamiga.library/CheckLock
transamiga.library/CloseBBSLine
transamiga.library/ConAbortRead
transamiga.library/ConCheckRead
transamiga.library/ConQueueRead
transamiga.library/DropDTR
transamiga.library/FixString
transamiga.library/FreeDriveSpace
transamiga.library/LogEntry
transamiga.library/NewBBSLine
transamiga.library/ObtainLine
transamiga.library/OutStr
transamiga.library/PostNodeMsg
transamiga.library/RaiseDTR
transamiga.library/ReleaseLine
transamiga.library/SaveMsgText
transamiga.library/SerFlush
transamiga.library/SerQuery
transamiga.library/SerReadChar
transamiga.library/SerReadData
transamiga.library/SerWrite
transamiga.library/SerWriteLen
transamiga.library/SetSerParams
transamiga.library/Notes


transamiga.library/ANSIWrite                   transamiga.library/ANSIWrite

    NAME
      ANSIWrite  - Writes a string, converting ANSI codes.

    SYNOPSIS
      VOID ANSIWrite(struct BBSLine *line, char *ch);
      -6c           d1                    a0

    FUNCTION
      Writes the string to the terminal window.  This provides
      high-powered ANSI emulation, capable of handling most Amiga and IBM
      ANSI codes, including 16-colour ANSI.  This ANSI emulation is
      significantly faster than the console.device with cursor on, and
      about the same speed as the console.device with cursor off.  It
      properly adjusts to different fonts sizes, system fonts and window
      sizes.  It does not update the position of the cursor sprite.


transamiga.library/BBSCmd                           transamiga.library/BBSCmd

    NAME
      BBSCmd  - Send an ARexx message to a line

    SYNOPSIS
      int BBSCmd(int linenum, char *cmd, char *buf);
      -102       d0           a0         a1

    FUNCTION
      Sends an ARexx command to a BBS line currently executing an ARexx
      macro.  The result code of that command is returned, and any string
      info returned is copied into the buffer pointed to by buf.  Any
      ARexx command that TransAmiga normally understands may be sent, but
      you must be careful only to use this function when you know that
      TransAmiga is going to be listening to its ARexx port.  Normally,
      only programmes actually started from within an ARexx macro using
      "address command ..." will use this function.

      Note that though you could perform all I/O simply bby sending ARexx
      commands.  However, this is not recommended for reasons of speed.
      For example, you will find it significantly faster to use
      ANSIWrite() and SerWrite() to send text than using the SEND ARexx
      command via BBSCmd().  For more involved I/O, such as displaying a
      text file, you will however probably prefer to use send ARexx
      commands.

    EXAMPLE
      You must also be sure that the command sent is as TransAmiga expects
      to see it.  For example, while in ARexx you might say:

        textpath='BBS:Text/'
        sendfile textpath'MyFile'

      But TransAmiga will actually see this as:

        SENDFILE BBS:Text/MyFile

      As ARexx will capitalize the command, expand all variables and
      remove quotation marks.  So to issue this command with BBSCmd(),
      you would use:

        rc=BBSCmd(bbsline,"SENDFILE BBS:Text/MyFile",buf);

      Be careful with commands like PROMPT, where TransAmiga still expect
      to see some quotation marks (see the TransAmiga.Doc for info on
      this).


transamiga.library/BBSLineInfo               transamiga.library/BBSLineInfo

    NAME
      BBSLineInfo  - Returns the BBS line structure of a line number

    SYNOPSIS
      ULONG BBSLineInfo(int linenum);
      -42               d1

    FUNCTION
      Returns the address of a BBSLine structure for the line number asked
      for, or NULL if a line has not been opened under that number.
      This function should only be used when no I/O needs to be done
      through the line asked for.  For all but the most simplest of tasks,
      use ObtainLine()/ReleaseLine() instead.


transamiga.library/CheckCarrier             transamiga.library/CheckCarrier

    NAME
      CheckCarrier  - Determines if carrier is present

    SYNOPSIS
       int CheckCarrier(struct BBSLine *line);
       -4e              d1

    FUNCTION
      Returns TRUE if carrier is present, or FALSE if it is not.  It will
      also return TRUE if there is no serial device for that line, and if
      DTR is low.


transamiga.library/CheckLock                   transamiga.library/CheckLock

    NAME
      CheckLock  - See if something is locked.

    SYNOPSIS
      int CheckLock(int what);
      -84           d1

    FUNCTION
      Returns either TRUE or FALSE depending on whether the resources
      asked for is locked.  See the header files for possible values of
      what.

    BUGS
      The value returned will only be meaningful if a copy of TransAmiga
      is currently running.


transamiga.library/CloseBBSLine             transamiga.library/CloseBBSLine

    NAME
      CloseBBSLine  - De-initializes a BBS line

    SYNOPSIS
      VOID CloseBBSLine(struct BBSLine *line);
      -3c               d1

    FUNCTION
      Releases all resources that were opened when NewBBSLine() was called.
      Each call you make to NewBBSLine() should have a matching
      CloseBBSLine() call to close down.


transamiga.library/ConAbortRead             transamiga.library/ConAbortRead

    NAME
      ConAbortRead  - Aborts the read request

    SYNOPSIS
      VOID ConAbortRead(struct BBSLine *line);
      -7e               d1

    FUNCTION
      Does an AbortIO() of the console read request, if one is still
      pending.  If there isn't, it simply does nothing, so it is always
      safe to call.

    EXAMPLE
      ConQueueRead(), ConCheckRead() and ConAbortRead() were all designed
      specifically for TransAmiga's needs, and therefore may not be suited
      to your applications.  However, this is typically how they would be
      used:

      First, make sure there are no outstanding requests:

        ConAbortRead(line);
        ConQueueRead(line,ch);

      Then, to check if a key has been pressed, call queue the read with
      ConQueueRead() (note that reads can be aborted by the BBS when you
      don't expect it, so you should call ConQueueRead() often), then
      ConCheckRead() to see if it says a character has been entered.  If it
      does, double-check this by seeing if the character is non-zero.  If it
      is, copy the character out of the buffer and queue up a new read:

        ConQueueRead(line,ch);
        if (ConCheckRead(line)==1)
        {
            if (ch[0]!=0)
            {
                c=ch[0];
                ConQueueRead(line,ch);
            }
        }

      Finally, before your programme exits, be sure to call ConAbortRead()
      so no outstanding requests are still pending:

        ConAbortRead(line);


transamiga.library/ConCheckRead             transamiga.library/ConCheckRead

    NAME
      ConCheckRead  - Checks if a character has been received

    SYNOPSIS
      int ConCheckRead(struct BBSLine *line);
      -78              d1

    FUNCTION
      Checks if the read request has completed and returns either 0 (if it
      has not) or 1 (if it has).  The character will be in the buffer you
      passed to ConQueueRead().

      This function will also update the position of the cursor in your
      window if the window is active.

    BUGS
      Sometimes ConCheckRead() will say that a character has arrived, but
      your buffer will contain 0.  Your input routine should therefore
      furthur check to make sure a non-zero value is in your character
      buffer.

    EXAMPLE
      See ConAbortRead().


transamiga.library/ConQueueRead             transamiga.library/ConQueueRead

    NAME
      ConQueueRead  - Queues a character read from the console.device

    SYNOPSIS
      VOID ConQueueRead(struct BBSLine *line, char *ch);
      -72               d1                    a0

    FUNCTION
      Starts up an asynchronous read of one character from the
      console.device.  The character will be placed in the location
      pointed to by ch.  Multiple read-requests can not be queued up
      simultaneously, i.e. if a request is already queued, ConQueueRead
      will do nothing.

    EXAMPLE
      See ConAbortRead().


transamiga.library/DropDTR                       transamiga.library/DropDTR

    NAME
      DropDTR  - Lowers serial DTR

    SYNOPSIS
      VOID DropDTR(struct BBSLine *line);
      -8a          d1

    FUNCTION
      Drops DTR on the specified line's serial device.  When DTR is low,
      any attempts to do any serial I/O will simply result in nothing
      happening.

    BUGS
      There is no easy way of dropping DTR on the Amiga, other than to
      close all instances of the unit of the serial device in use.  This
      function will close the serial device that TransAmiga opened (if you
      have direct access to the BBSLine structure) or the serial device
      opened when you ObtainLine()'ed a BBSLine structure.  It can't do
      anything about others that have the serial device open (such as a
      frontend mailer), so if there are such programmes running, DTR will
      not be dropped.


transamiga.library/FixString                   transamiga.library/FixString

    NAME
      FixString  - Fixes the capatilization of a string

    SYNOPSIS
      void FixString(char *name)
      -f0            a0

    FUNCTION
      Tries to fix the capitilization of someone's name.  The first
      character, and every character after any punctuation will be
      capitalized, all other characters will be in lower-case.  This can
      be useful as TransAmiga stores user names all in capitals.

      FixString now also nows about names beginning with 'Mac' and 'Mc',
      in which cases the next letter after them will be capitalized, and
      it also knows about 'de' by itself, in which case the d will be
      lowercase.


transamiga.library/FreeDriveSpace         transamiga.library/FreeDriveSpace

    NAME
      FreeDriveSpace  - returns the number of kilobytes free on a drive.

    SYNOPSIS
      LONG FreeDriveSpace(char *dev);
      -30            a0

    FUNCTION
      Returns the number of free kilobytes on dev.  Note that dev doesn't
      actually have to be the name of a physical device, it can be a
      directory or an assignment, and the number of free kilobytes on the
      device on which that directory or assignment resides will be
      returned.


transamiga.library/LogEntry                       transamiga.library/LogEntry

    NAME
      LogEntry  - Add a formatted log entry to the specified log file.

    SYNOPSIS
      VOID LogEntry(char *symbol, char *str, char *logfile);
      -2a           d1           a0         a1

    FUNCTION
      Appends str to logfile, with symbol as the identifier.  It is
      formatted with the identifier first, followed by the date and time
      then the log string.  If the file does not exist, it creates a new
      one.  Symbol should be a one character string.


transamiga.library/NewBBSLine                 transamiga.library/NewBBSLine

    NAME
      NewBBSLine  - Sets up a new line for the BBS.

    SYNOPSIS
      int NewBBSLine(struct BBSLine *line);
      -36            d1

    FUNCTION
      Does all the necessary setup for a new BBS line, given a properly
      initialized BBSLine struct.  The only fields of this structure that
      need to be set are bl_Number and bl_Window.  If no font name and
      size is given, no font will be set for your window.  If no serial
      device name is given, then no serial device will be open, and all
      serial I/O functions for that line will simply do nothing.  If you
      do not set bl_Screen, then the Workbench screen will be used (or the
      default public screen for those running Release 2).  You should set
      the bl_Status field to something meaningful.

      See transamiga.h for more information on specific fields in the
      BBSLine structure and for return codes.

      Nothing other than TransAmiga itself should ever actually have a
      need for this function, as doors spawned from the BBS do not setup
      their own line.


transamiga.library/ObtainLine                   transamiga.library/ObtainLine

    NAME
      ObtainLine  - Obtain access to a BBSLine structure

    SYNOPSIS
      LONG ObtainLine(LONG linenum, struct BBSLine *linebuf);
      -114            d1            a0

    FUNCTION
      Gains access to the line asked for.  A copy is made of the BBSLine
      structure, and is put into the buffer pointed to by linebuf.  An
      error code is returned (see transamiga.h) or 0 if there was no
      error.

    EXAMPLE
      struct BBSLine line_buf;
      LONG ret,bbsline=0;

      ret=ObtainLine(bbsline,&line_buf);
      ...
      ReleaseLine(&line_buf);


transamiga.library/OutStr                            transamiga.library/OuStr

    NAME
      OutStr  - Simple unbuffered text output to stdout.

       SYNOPSIS
      VOID OutStr(char *str);
      -24         a0

    FUNCTION
      Simply prints the supplied string to Output().  Absolutely nothing
      fancy is done, just a quick way to ouput a string.


transamiga.library/PostNodeMsg                transamiga.library/PostNodeMsg

    NAME
      PostNodeMsg  - Sends a message to another line.

    SYNOPSIS
      void PostNodeMsg(struct BBSLine *line, int linenum, char *msg)
      -c6              d1

    FUNCTION
      Sends an online message to the indicated line number.  If linenum is
      greater than 100, then the message will be broadcast to all lines
      except the current one.  Passing the BBSLine structure of the current
      line (or a copy thereof) is optional, but recommended if possible.
      For example, a door programme SHOULD pass it, while an external
      programme talking to the BBS wouldn't be able to so it shouldn't.

    BUGS
      In versions of TransAmiga previous to v1.11, a completely different
      method of passing messages was used that involved the setting of the
      bl_Message field in the BBSLine structure.  This method was poor,
      and that's why it was replaced, however, some applications may have
      depended on this and will therefore break under v1.11 and above.


transamiga.library/RaiseDTR                     transamiga.library/RaiseDTR

    NAME
      RaiseDTR  - Raises serial DTR

    SYNOPSIS
      VOID RaiseDTR(struct BBSLine *line);
      -90           d1

    FUNCTION
      Raises the DTR for the serial device of the specified line.  If the
      line isn't using serial.device, then it will just re-OpenDevice()
      the read and write requests.


transamiga.library/ReleaseLine                 transamiga.library/ReleaseLine

    NAME
      ReleaseLine  - Release an obtained line

    SYNOPSIS
      VOID ReleaseLine(struct BBSLine *line);
      -11a             a0

    FUNCTION
      Relinquishes control over a line that you have obtained using
      ObtainLine().  Every call to ObtainLine() must be matched by a call
      to ReleaseLine().  Once you have called this function, you may no
      longer use the BBSLine structure you've obtained.


transamiga.library/SaveMsgText                 transamiga.library/SaveMsgText

    NAME
      SaveMsgText  - Save the text of a message to a file

    SYNOPSIS
      int SaveMsgText(char *infile, char *outfile, LONG msgnum, LONG type,
      -108            a0            a1             d0           d1
                      LONG marg, struct MsgHeader *header)
                      d2         a2
    FUNCTION
      Saves an FTS-0001 message file, given by infile and msgnum, to the
      given outfile.  If outfile exists, the text will be appended to it.
      It will be formatted to fit into a margin of marg.  header is not
      currently used, but you MUST pass 0 in the meantime.  Type allows
      you to specify what the output will look like, see transamiga.h for
      the definitions of the various flags.


transamiga.library/SerFlush                     transamiga.library/SerFlush

    NAME
      SerFlush  - Flushes the serial device's input buffer

    SYNOPSIS
      VOID SerFlush(struct BBSLine *line);
      -66           d1

    FUNCTION
      Does a CMD_CLEAR on the lines serial read request.


transamiga.library/SerQuery                     transamiga.library/SerQuery

    NAME
      SerQuery  - Query how many characters the serial device has waiting

    SYNOPSIS
      ULONG SerQuery(struct BBSLine *line);
      -ba            d1

    FUNCTION
      Returns the number of characters waiting to be read from the serial
      device of the given line, but doesn't actually read any.


transamiga.library/SerReadChar               transamiga.library/SerReadChar

    NAME
      SerReadChar  - Reads a character from the serial port

    SYNOPSIS
      LONG SerReadChar(struct BBSLine *line, char *ch);
      -60              d1                    a0

    FUNCTION
      Reads a single character from the serial port if there is one
      waiting, and places it in the buffer *ch.  Returns the number of
      characters read (either 0 or 1).  Always returns 0 if there is no
      serial device open or DTR is low.


transamiga.library/SerReadData               transamiga.library/SerReadData

    NAME
      SerReadData  - Gets all waiting characters from the serial port

    SYNOPSIS
      LONG SerReadData(struct BBSLine *line, char *ch);
      -5a              d1                    a0

    FUNCTION
      Reads all characters waiting at the serial port into the buffer *ch.
      Returns the number of characters actually read.  Always returns 0 if
      there is no serial device open or DTR is low.


transamiga.library/SerWrite                     transamiga.library/SerWrite

    NAME
      SerWrite  - Outputs a string to the serial port

    SYNOPSIS
      VOID SerWrite(struct BBSLine *line, char *ch);
      -54           d1                    a0

    FUNCTION
      Simply sends the specified string to the given line's serial port.


transamiga.library/SerWriteLen               transamiga.library/SerWriteLen

    NAME
      SerWriteLen  - Outputs a string to the serial port

    SYNOPSIS
      VOID SerWriteLen(struct BBSLine *line, char *ch, ULONG len);
      -ae              d1                    a0        a1

    FUNCTION
      Simply sends the specified string of the given length to the line's
      serial port.


transamiga.library/SetSerParams             transamiga.library/SetSerParams

    NAME
      SetSerParams  - Changes the baud rate for a line

    SYNOPSIS
      VOID SetSerParams(struct BBSLine *line, ULONG baud);
      -48               d1                    d2

    FUNCTION
      Adjusts the baud rate of the serial device for the line given.  Safe
      to call if the serial device is not open.


transamiga.library/Notes                           transamiga.library/Notes

    This library is still under development, so there are functions still to
    be added, and existing functions may be changed.  Also, there are a
    few private functions that are not documented here (since they're
    private).